// 版权所有2011 Go作者。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

// 此文件实现了NewPackage。

package ast

import (
	"fmt"
	"go/scanner"
	"go/token"
	"strconv"
)

type pkgBuilder struct {
	fset   *token.FileSet
	errors scanner.ErrorList
}

func (p *pkgBuilder) error(pos token.Pos, msg string) {
	p.errors.Add(p.fset.Position(pos), msg)
}

func (p *pkgBuilder) errorf(pos token.Pos, format string, args ...any) {
	p.error(pos, fmt.Sprintf(format, args...))
}

func (p *pkgBuilder) declare(scope, altScope *Scope, obj *Object) {
	alt := scope.Insert(obj)
	if alt == nil && altScope != nil {
		// 查看altScope中是否存在冲突声明
		alt = altScope.Lookup(obj.Name)
	}
	if alt != nil {
		prevDecl := ""
		if pos := alt.Pos(); pos.IsValid() {
			prevDecl = fmt.Sprintf("\n\tprevious declaration at %s", p.fset.Position(pos))
		}
		p.error(obj.Pos(), fmt.Sprintf("%s redeclared in this block%s", obj.Name, prevDecl))
	}
}

func resolve(scope *Scope, ident *Ident) bool {
	for ; scope != nil; scope = scope.Outer {
		if obj := scope.Lookup(ident.Name); obj != nil {
			ident.Obj = obj
			return true
		}
	}
	return false
}

// 导入程序解析到包对象的导入路径。
// 导入映射记录已导入的包，
// 按包id（规范导入路径）索引。
// 导入程序必须确定规范导入路径，
// 检查映射，查看它是否已存在于导入映射中。
// 如果是，进口商可以返回地图条目。否则，导入程序应该将给定路径的包数据加载到新的*对象（pkg）中，在导入映射中记录pkg，然后返回pkg。
type Importer func(imports map[string]*Object, path string) (pkg *Object, err error)

// NewPackage从一组文件节点创建一个新的包节点。它解析文件间未解析的标识符，并相应地更新每个文件的未解析列表。如果提供了非nil导入程序和宇宙范围，则它们是
// 用于解析任何包文件中未声明的标识符。任何
// 剩余的未解析标识符都报告为未声明。如果文件
// 属于不同的软件包，则选择一个软件包名称，报告并忽略具有
// 不同软件包名称的文件。
// 结果是一个包节点和一个扫描仪。如果有错误，请列出错误列表。
// 
func NewPackage(fset *token.FileSet, files map[string]*File, importer Importer, universe *Scope) (*Package, error) {
	var p pkgBuilder
	p.fset = fset

	// 完整的包范围
	pkgName := ""
	pkgScope := NewScope(universe)
	for _, file := range files {
		// 包名称必须与
		switch name := file.Name.Name; {
		case pkgName == "":
			pkgName = name
		case name != pkgName:
			p.errorf(file.Package, "package %s; expected %s", name, pkgName)
			continue // 忽略此文件
		}

		// 收集包范围中的顶级文件对象
		for _, obj := range file.Scope.Objects {
			p.declare(pkgScope, nil, obj)
		}
	}

	// 导入的包ID到包对象的包全局映射
	imports := make(map[string]*Object)

	// 使用导入和解析标识符完成文件范围
	for _, file := range files {
		// 如果文件属于不同的包，则忽略该文件
		// （已报告错误）
		if file.Name.Name != pkgName {
			continue
		}

		// 通过处理所有导入来构建文件范围
		importErrors := false
		fileScope := NewScope(pkgScope)
		for _, spec := range file.Imports {
			if importer == nil {
				importErrors = true
				continue
			}
			path, _ := strconv.Unquote(spec.Path.Value)
			pkg, err := importer(imports, path)
			if err != nil {
				p.errorf(spec.Path.Pos(), "could not import %s (%s)", path, err)
				importErrors = true
				continue
			}
			// 如果是本地包名，则忽略TODO（gri）！=如果提供“.”，则即使导入失败，也可以继续进行全局标识符解析。考虑一下在这里调整逻辑。

			// 本地名称覆盖导入的包名称
			name := pkg.Name
			if spec.Name != nil {
				name = spec.Name.Name
			}

			// 将导入添加到文件作用域
			if name == "." {
				// 将导入的作用域与文件作用域合并
				for _, obj := range pkg.Data.(*Scope).Objects {
					p.declare(fileScope, pkgScope, obj)
				}
			} else if name != "_" {
				// 在文件作用域
				// （不要在文件范围内重复使用pkg，而是创建一个新对象；Decl字段不同
				// 对于不同的文件）
				obj := NewObj(Pkg, name)
				obj.Decl = spec
				obj.Data = pkg.Data
				p.declare(fileScope, pkgScope, obj)
			}
		}

		// 解析标识符
		if importErrors {
			// 在没有正确导入的情况下不要使用宇宙范围
			// （宇宙中的对象可能会被导入隐藏；
			// 如果缺少导入，标识符可能会被解析为宇宙对象错误）
			pkgScope.Outer = nil
		}
		i := 0
		for _, ident := range file.Unresolved {
			if !resolve(fileScope, ident) {
				p.errorf(ident.Pos(), "undeclared name: %s", ident.Name)
				file.Unresolved[i] = ident
				i++
			}

		}
		file.Unresolved = file.Unresolved[0:i]
		pkgScope.Outer = universe // 重置宇宙范围
	}

	p.errors.Sort()
	return &Package{pkgName, pkgScope, imports, files}, p.errors.Err()
}
